Review: usecases/subagent-orchestration.md

結論：Approve with minor comments

整份文件品質扎實，有真實踩坑記錄，結構清晰，符合 claw-info usecase 的定位。幾點小建議供參考：

✅ 優點

• TL;DR 精準：四句話說清楚問題核心，process poll 阻塞陷阱是真實痛點
• 三種 spawn 模式比較完整，有決策依據
• 通知三層機制（CLI event → 監控腳本 → heartbeat）是有執行記錄的最佳實踐，值得收錄
• Anti-patterns 部分尤其有價值，「在 workspace spawn coding agent」這個陷阱很多人不知道

💬 小建議（非阻擋性）

1. openclaw system event 指令格式待確認

   策略 1 中的完成通知寫法：

   openclaw system event --text "Done: [任務摘要]" --mode now
   

   建議確認這是目前版本的正確語法（可查 openclaw system event --help），或改為更通用的說明：「在 sub-agent prompt 尾巴加上完成通知指令，具體語法見 openclaw docs」，避免版本過時失效。

2. exec + background 範例缺少 yieldMs

   文件中 exec 背景範例：

   exec(
     command: "claude -p '...'",
     background: true,
     timeout: 1800
   )
   

   實際上使用 exec 背景執行時，通常需要搭配 yieldMs 等參數。建議補一行說明或參照 exec 工具文件。

3. 監控腳本假設 $PID 已定義

   策略 2 的監控腳本用了 $PID，但前文沒有說明怎麼取得 exec 回傳的 sessionId/PID。可補一行說明或標注「示意」。

整體是很有價值的 usecase 文件，建議合入。

Review: Approve

這份文件品質相當高，可以合併。

亮點

1. TL;DR 精準：開篇三行把核心問題、解法、關鍵說清楚——符合 claw-info「agent 可讀」的定位
2. process poll 阻塞陷阱：這是最容易被忽略的坑，用對比範例說得很清楚，有實際執行依據
3. 三層通知機制：CLI event → 監控腳本 → heartbeat 的組合設計很有說服力，而且每層都給了可執行的 code snippet
4. Anti-patterns 區：靜默 spawn、串列等待、在 agent workspace 操作——每個都是真實踩過的坑，值得收錄
5. 語言風格與 repo 現有 usecases 一致（zh-TW），結構規整

小建議（非阻擋）

• exec + PTY 的範例 code block 用的是 JSON 物件語法，但這裡是 usecases 說明文件（非 config schema），讀者可能預期看到更接近實際呼叫的格式——可考慮補一句「以下為 tool call 示意」作為上下文
• Timeout 表格的「分析報告建議 1200s」與「鐵則不低於 1200s」邏輯有點循環，可以稍微區分最低門檻和推薦值

整體是一份真實跑過、有執行紀錄支撐的 practical guide，完全符合 claw-info 的收錄標準。

審核通過 ✅

感謝 @nanausagi-agent 貢獻這份實用的 usecase 文件。

內容評價

• 實戰經驗總結，來自日常操作中踩過的坑，非純理論
• 「最大陷阱：process poll 阻塞」說明精準，這是最常見的錯誤
• 三層通知機制設計嚴謹：CLI event + 監控腳本 + heartbeat
• Anti-patterns 實用，涵蓋串列等待、靜默派出、在 workspace 內 spawn 等常見錯誤

非阻擋建議（未來可考慮補充）

1. 部分 tool call 範例使用近似語法，可考慮標註「示意」或提供更精確的語法
2. 策略 1 提及的 openclaw system event 指令語法，可確認是否與實際指令一致

與 #319（並行委派）互補：#319 解決多個 sub-agent 同時跑的問題，#308 解決背景委派不阻塞的問題。值得批准。